<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Localization : DataMapper ORM - User Guide</title>

<link rel="shortcut icon" type="image/png" href="../images/favicon.png" />
<link rel="stylesheet" type="text/css" media="all" href="../css/userguide.css" />
<link rel="alternate" type="application/rss+xml" title="Datamapper ORM Updates Feed" href="/rss.xml" />

<meta http-equiv="expires" content="-1" />
<meta http-equiv= 'pragma' content="no-cache" />
<meta name="robots" content="all" />

</head>

<body>

<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top">&nbsp;</a><a id="nav_toggle" href="#"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>DataMapper ORM</h1></td>
<td id="breadcrumb_right"><a href="toc.html">Table of Contents Page</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->

<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="/">Datamapper ORM Home</a> &nbsp;&#8250;&nbsp;
<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
Localization
</td>
</tr>

</table>
<!-- END BREADCRUMB -->

<br clear="all" />


<!-- START CONTENT -->
<div id="content">


<h1>Localization</h1>

<div class="example">
	<h4>Example Application</h4>
	<p>You can see this feature used in all example application models:</p>
	<div class="paths">
		ZIP/<b>examples/application/<br/>
		&nbsp;&nbsp;&nbsp;&nbsp;&raquo; models/ <br/>
		&nbsp;&nbsp;&nbsp;&nbsp;&raquo; language/english/</b>
	</div>
</div>

<p>
	Datamapper ORM can automatically load in a model-specific language file, and then it can set language-specific labels on each field or relationship.
	When using this method, there is no need to specify the <dfn>label</dfn> key in the <var><i>$validation</i></var> array.
</p>
<p>
	It uses the built-in CodeIgniter library for localizing.
	For more information on this library, please see <a href="http://codeigniter.com/user_guide/libraries/language.html">the CodeIgniter manual</a>.
</p>
<div class="note">
	If you want Datamapper ORM to automatically load in the language files, and have different languages available on your website,
	you will probably need a different CodeIgniter library to handle switching the language <strong><em>before</em></strong> creating any Datamapper ORM models.<br/>
	Also see <a href="#Handling.Language.Changes">Handling Language Changes</a> below.
</div>

<h4>Subsections:</h4>
<ul>
	<li>Localization
		<ul>
			<li><a href="#Recommended.Method">Recommended Method</a> - Get started easily</li>
			<li><a href="#Alternate.Method">Alternate Method</a> - Different Technique</li>
			<li><a href="#Handling.Language.Changes">Handling Language Changes</a> - Changing the default language</li>
			<li><a href="#Configuration">Configuration</a> - Config Options</li>
		</ul>
	</li>
	<li><a href="#Localizing.Helper.Methods">Localizing Helper Methods</a> - Helper methods for localizing
		<ul>
			<li><a href="#localize_label">localize_label</a> - Get a per-model, per-field localized string</li>
			<li><a href="#localize_by_model">localize_by_model</a> - Custom localizations</li>
		</ul>
	</li>
</ul>

<h2 id="Recommended.Method">Recommended Method</h2>
<p>The easiest way to add localization is use the following language file standards:</p>
<ul>
	<li>
		For each model, create a <a href="http://codeigniter.com/user_guide/libraries/language.html">new language file</a> under <var>application/language/&lt;lang&gt;/</var>
		named <var>model_<dfn>${model}</dfn>_lang.php</var>, where <dfn>${model}</dfn> is replaced with the model's <var><i>$model</i></var> property.
	</li>
	<li>Using the CodeIgniter standard, create a key for each <dfn>field</dfn> (and, optionally, relationship) using the format <dfn>${model}<var>_</var>${field}</dfn>.</li>
</ul>
<h3>Example</h3>
<pre><div class="lineNums"> 1
 2
 3
 4
 5
 6
 7
 8</div><var>&lt;?php
</var><samp>// Language File for Comment Model
</samp><var>$lang</var><kbd>[</kbd><dfn>'comment_comment'</dfn><kbd>]         = </kbd><dfn>'Comment'</dfn><kbd>;
</kbd><var>$lang</var><kbd>[</kbd><dfn>'comment_bug'</dfn><kbd>]             = </kbd><dfn>'Bug'</dfn><kbd>;
</kbd><var>$lang</var><kbd>[</kbd><dfn>'comment_user'</dfn><kbd>]            = </kbd><dfn>'User'</dfn><kbd>;

</kbd><samp>/* End of file model_comment_lang.php */
/* Location: ./application/language/english/model_comment_lang.php */</samp>
</pre>

<p>Believe it or not, that's it!  You don't even have to load in the language file.  You can easily create multiple-languages by duplicating the language files for each model into a different language folder, and loading them as needed.</p>
<p class="note">If you are upgrading from a version of Datamapper ORM older than 1.7.0, make sure you add the new <var><i>lang_file_format</i></var> configuration option, and set it to <dfn>model_${model}</dfn>.</p>

<h2 id="Alternate.Method">Alternate Method</h2>
<p>If you don't want automatic loading, or you prefer hard-coding the labels, you can also manually set the label field using the format <var>lang:<dfn>lang_key</dfn></var>.</p>
<p>
	Datamapper ORM will automatically replace that label with the appropriate language value, if it exists.
	Using this method, you can still have Datamapper ORM automatically load the language file using the <var><i>lang_file_format</i></var> property.
</p>
<h3>Example</h3>
<pre>
<kbd>class </kbd><var>User </var><kbd>extends </kbd><var><u>DataMapper</u> </var><kbd>{
    var </kbd><var><i>$validation</i> </var><kbd>= array(
        </kbd><dfn>'name' </dfn><kbd>=&gt; array(
            </kbd><dfn>'label' </dfn><kbd>=&gt; </kbd><dfn>'lang:user.fields.Name'</dfn><kbd>,
            </kbd><dfn>'rules' </dfn><kbd>=&gt; array(</kbd><dfn>'required'</dfn><kbd>)
        )
    );
}</kbd>
</pre>


<h2 id="Handling.Language.Changes">Handling Language Changes</h2>
<p>
	The best solution is to somehow determine the language before loading any models.
	If you can do that, then simply change <var><b>$this</b><kbd>-></kbd>config<kbd>-></kbd>config<kbd>[</kbd><dfn>'language'</dfn><kbd>]</kbd></var> and all models will use that.
</p>
<p>However, if you need changing the language dynamically, such as when loading a user's preference, you can use <var><u>reinitialize_model</u></var> to <a href="utility.html#reinitialize_model">to reload the language</a>.</p>
<p>Please read the linked section carefully, however, as it doesn't update other models, or any other already existing objects, so it should be called as early as possible.</p>

<h2 id="Configuration">Configuration</h2>
<p>
	Most of the time, simply standardizing your language file settings will be all you need to do.
	However, Datamapper ORM is very flexible in configuring which files to load, and how to look for the language keys.
</p>
<p>Both of the properties can be set globally (in the <a href="config.html">config file</a>, or on a per-model basis.</p>
<h3>Loading the Language File</h3>
<p>
	The language file is specified by the configuration option <var><i>lang_file_format</i></var>.
	If it is not provided, is empty, or the file does not exist, no language file will be loaded by default.
</p>
<p>The default format is <kbd>model_${model}</kbd>.</p>
<p>The option has two properties that can be used to dynamically change the file name.  Please note that these must be specified exactly, including the dollar-sign ($) and braces ({}).</p>
<ul>
	<li><b>${model}</b>: This is replaced by the class's <var><i>$model</i></var> property.</li>
	<li><b>${table}</b>: This is replaced by the class's <var><i>$table</i></var> property.</li>
</ul>
<p>
	The result of the updated property is passed directly to <var>lang->load()</var>.
	Note: The actual file name must end in <var>_lang.php</var>.
</p>
<p>(If the file does not exist, Datamapper ORM won't attempt load it.  This prevents errors when you don't have a language file for a given model.)</p>

<h3>Loading the Field Labels</h3>
<p>The keys for the field labels is specified by the configuration option <var><i>field_label_lang_format</i></var>.</p>
<p>The default format is <kbd>${model}_${field}</kbd>.</p>
<p>In addition to the model and table properties, each field key has an additional property:</p>
<ul>
	<li><b>${field}</b>: This is replaced by the field's name.</li>
</ul>

<p>&nbsp;</p>

<h1 id="Localizing.Helper.Methods">Localizing Helper Methods</h1>
<p>
	You can actually use the new localizing tools for more than just field labels.
	They can also be used to dynamically load in properties based on model, table, and field names at any time, using the following two methods.
</p>
<h2 id="localize_label">$object->localize_label($field)</h2>
<div class="example">
	<h4>Example Application</h4>
	<p>This feature is used in the __toString method of many models:</p>
	<div class="paths">
		ZIP/<b>examples/application/<br/>
		&nbsp;&nbsp;&nbsp;&nbsp;&raquo; models/</b>
	</div>
</div>
<p>
	This method will use the <var><i>field_label_lang_format</i></var> property to localize a given <var>$field</var>.
</p>
<h3>Example</h3>
<pre>
<kbd>function </kbd><var>__toString</var><kbd>() {
    return </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var><u>exists</u></var><kbd>() ? </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var>name </var><kbd>: </kbd><var><b>$this</b></var><kbd>-&gt;</kbd><var><u>localize_label</u></var><kbd>(</kbd><dfn>'unset'</dfn><kbd>);
}</kbd>
</pre>

<h2 id="localize_by_model">$object->localize_by_model($key, <em>$field</em>)</h2>
<p>
	This method will automatically replace <dfn>${model}</dfn> and <dfn>${table}</dfn> in the given <var>$key</var>, and return the localized string.
	If <var>$field</var> is passed, that replaces <dfn>${field}</dfn> in the <var>$key</var>.
</p>
<p>
	This may be useful for loading in other common localized strings.
	For example, you might use it in an <a href="extensions.html">extension</a> like this:
</p>
<pre>
<samp>// Returns a localized error string
</samp><kbd>function </kbd><var>localize_error</var><kbd>(</kbd><var>$object</var><kbd>, </kbd><var>$error</var><kbd>) {
    return </kbd><var>$object</var><kbd>-&gt;</kbd><var><u>localize_by_model</u></var><kbd>(</kbd><dfn>'${model}_error_${field}'</dfn><kbd>, </kbd><var>$error</var><kbd>);
}</kbd>
</pre>



</div>
<!-- END CONTENT -->


<div id="footer">
<p>
<span id="footer_previous">Previous Topic:&nbsp;&nbsp;<a href=""></a>
&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;</span>
<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
<a href="../index.html">User Guide Home</a>
<span id="footer_next">&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
Next Topic:&nbsp;&nbsp;<a href=""></a></span>
</p>
<div id="copyrights">
<p><a href="/">Datamapper ORM</a> &nbsp;&middot;&nbsp; Copyright &copy; 2010-2011 &nbsp;&middot;&nbsp; Harro "WanWizard" Verton</p>
<p><a href="license.html">Other License Information</a></p>
</div>
</div>

<script type="text/javascript" src="../js/mootools.js"></script>
<script type="text/javascript" src="../js/menu.js"></script>
<script type="text/javascript">
<!--
	window.addEvent('domready', function() {

		// Create Menu
		var menu = new Menu({
			basepath: '../',
			pagespath: ''
		});

	});
//-->
</script>
</body>
</html>
